Skip to content

Feature/esp webpush v2#4

Merged
zekageri merged 5 commits intomainfrom
feature/esp-webpush-v2
Mar 28, 2026
Merged

Feature/esp webpush v2#4
zekageri merged 5 commits intomainfrom
feature/esp-webpush-v2

Conversation

@zekageri
Copy link
Copy Markdown
Collaborator

@zekageri zekageri commented Mar 28, 2026 

## Summary

This PR cleans up the `esp-webPush` public transport API by renaming `Subscription` to `WebPushSubscription`, renaming `PushMessage.sub` to `PushMessage.subscription`, and removing app-level metadata fields (`deviceId`, `disabledTags`, and `deleted`) from the transport struct.

The motivation is to keep `esp-webPush` focused on Web Push transport concerns only, avoid collisions with generic `Subscription` types in consuming apps, and remove unused/non-transport fields from the library API.

Related issues: none linked.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [x] Breaking change (fix or feature that would cause existing functionality to change)
- [x] Refactor (code change that neither fixes a bug nor adds a feature)
- [x] Documentation update
- [ ] Build/CI

## Details

This PR changes the public API and internal implementation to consistently use `WebPushSubscription` instead of `Subscription`.

It also removes fields that do not belong in the transport-layer type:
- `deviceId`
- `disabledTags`
- `deleted`

`PushMessage.sub` was renamed to `PushMessage.subscription` to match the new type name and make the API clearer.

`validateSubscription()` now validates only the required Web Push transport fields:
- `endpoint`
- `p256dh`
- `auth`

README examples, API reference, the example sketch, and the changelog were updated to reflect the breaking rename and field removals.

Reviewer context:
- This intentionally does not add tag filtering or any replacement metadata field.
- This intentionally does not provide a compatibility alias; downstream code must migrate to the new names.
- The goal is to narrow the library API to pure Web Push transport data and leave app-level recipient policy outside the library.

## Testing

- [x] Builds locally
- [x] Unit tests added/updated
- [ ] Tested on target hardware/device (if applicable)

Tested with local PlatformIO compile checks:

```bash
/home/zekageri/.platformio/penv/bin/pio ci /home/zekageri/projects/esptoolkit/libs/esp-webPush/test/test_esp_webPush \
  --board esp32dev \
  --lib /home/zekageri/projects/esptoolkit/libs/esp-webPush \
  --project-option platform=https://github.com/pioarduino/platform-espressif32.git \
  --project-option build_unflags=-std=gnu++11 \
  --project-option build_flags=-std=gnu++17 \
  --project-option lib_deps=ArduinoJson@>=7.0.0
/home/zekageri/.platformio/penv/bin/pio ci /home/zekageri/projects/esptoolkit/libs/esp-webPush/examples/basic_web_push \
  --board esp32dev \
  --lib /home/zekageri/projects/esptoolkit/libs/esp-webPush \
  --project-option platform=https://github.com/pioarduino/platform-espressif32.git \
  --project-option build_unflags=-std=gnu++11 \
  --project-option build_flags=-std=gnu++17 \
  --project-option lib_deps=ArduinoJson@>=7.0.0

Both completed successfully.

Unit tests were updated for the renamed API, and a transport-only validation case was added to confirm the struct now requires only endpoint, p256dh, and auth.

Compatibility / Breaking Changes

This is a breaking API change.

Changes:

  • Subscription -> WebPushSubscription
  • PushMessage.sub -> PushMessage.subscription
  • Removed deviceId
  • Removed disabledTags
  • Removed deleted
  • Removed deleted-state validation from validateSubscription()

Migration steps:

  • Rename all usages of Subscription to WebPushSubscription
  • Rename all usages of PushMessage.sub to PushMessage.subscription
  • Remove any writes/reads of deviceId, disabledTags, and deleted
  • Move app-level recipient metadata or filtering logic outside esp-webPush

Risks and Mitigations

Main risk:

  • Downstream users will get compile errors because there is no compatibility alias.

Mitigations:

  • README and example code were updated to the new API.
  • Changelog includes an explicit breaking-change note.
  • Tests were updated to cover the renamed API and transport-only validation behavior.

Secondary risk:

  • Removing deleted changes preflight validation behavior.

Mitigation:

  • This was intentional and documented; the transport struct now represents only Web Push credentials.

Checklist

  • Code follows project style and conventions
  • All tests pass locally
  • Documentation updated (README, examples, comments)
  • No secrets, credentials, or sensitive data committed
  • Linked issue(s) and relevant context provided

Note: local compile checks passed, but I am not marking "All tests pass locally" because I did not complete a separate ESP-IDF smoke verification beyond the Arduino-side compile checks.

Environment

  • Toolchain/SDK versions: PlatformIO pio ci, platform-espressif32 from https://github.com/pioarduino/platform-espressif32.git, ArduinoJson >= 7.0.0, C++17
  • OS and version: Linux local development environment
  • Other relevant environment details: validation performed against esp32dev target

@zekageri zekageri merged commit 71200ef into main Mar 28, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@zekageri